﻿//---------------------------------------------------------------------------------
// Copyright 2011 Microsoft Corporation
// Licensed under the Microsoft Public License (MS-PL) (the "License"); 
// You may not use this file except in compliance with the License. 
// You may obtain a copy of the License at http://www.opensource.org/licenses/ms-pl.html
// THIS CODE IS PROVIDED *AS IS* BASIS, WITHOUT WARRANTIES OR 
// CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, 
// INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OR 
// CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, 
// MERCHANTABLITY OR NON-INFRINGEMENT. 
// See the Microsoft Public License (MS-PL) for the specific language governing 
// permissions and limitations under the License.
//---------------------------------------------------------------------------------
using System.Collections.Generic;
using Microsoft.Telco.Core.Interfaces.Advertising;
using Microsoft.Telco.Core.Interfaces.MMS;
using Microsoft.Telco.Core.Interfaces.SMS;

namespace Microsoft.Telco.Core.Interfaces
{
    /// <summary>
    /// Provides signatures for interacting with the Telco provider.
    /// </summary>
    public interface ITelcoProvider
    {
        /// <summary>
        /// Gets the advertisement.
        /// </summary>
        /// <param name="request">The request.</param>
        /// <returns>The requested advertisement</returns>
        IAdResponse GetAdvertisement(IAdRequest request);

        /// <summary>
        /// Creates a call between the origin and destination
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="originAddress">The origin of the call request.</param>
        /// <param name="destinationAddress">The remote endpoint to be connected on this call.</param>
        /// <param name="connectionText">Text provided on connection</param>
        /// <returns>The status of the call</returns>
        string CreateCall(string userId, string originAddress, string destinationAddress, string connectionText);

        /// <summary>
        /// Gets the MMS status.
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="messageId">The message id.</param>
        /// <returns>The message delivery status</returns>
        string GetMMSStatus(string messageId);

        /// <summary>
        /// Gets MMS messages for the application.
        /// </summary>
        /// <remarks>
        /// The invocation of GetMMSMessages retrieves all the MMS messages received that fullfil the
        /// criteria identified by UserId.
        /// </remarks>
        /// <param name="userId">The id of the user sending the message</param>
        /// <returns>The collection of messages for the specified user</returns>
        List<IMMSMessage> GetMMSMessages(string userId);

        /// <summary>
        /// Sends an MMS message.
        /// </summary>
        /// <param name="message">The message to send</param>
        /// <returns>The message Id that can be used to query message delivery status</returns>
        string SendMMSMessage(IMMSMessage message);

        /// <summary>
        /// Sends an SMS message.
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="originAddress">The phone number the message comes from</param>
        /// <param name="destinationAdresses">Phone numbers to send SMS to.</param>
        /// <param name="message">The SMS message.</param>
        /// <returns>The message Id that can be used to query message delivery status</returns>
        string SendSMSMessage(string userId, string originAddress, string[] destinationAddresses, string smsText);

        /// <summary>
        /// Gets the SMS status.
        /// </summary>
        /// <param name="userId">The id of the user sending the message</param>
        /// <param name="messageId">The message id.</param>
        /// <returns>The message delivery status</returns>
        ISMSDeliveryStatus[] GetSMSStatus(string userId, string messageId);

        /// <summary>
        /// Gets SMS messages for the application.
        /// </summary>
        /// <remarks>
        /// The invocation of GetSMSMessages retrieves all the SMS messages received that fullfil the
        /// criteria identified by userId. 
        /// </remarks>
        /// <param name="userId">The id of the user sending the message</param>
        /// <returns>A collection of messages for the user</returns>
        ISMSMessage[] GetSMSMessages(string userId);
    }
}
